<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Database - DBUtil class - Fuel Documentation</title>
	<link href="../../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../../assets/js/nav.js"></script>
	<script type="text/javascript" src="../../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('classes', '../../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>DBUtil Class</h2>

		<p>The DBUtil class allowes you to manage and perform routine opperations on your databases.</p>
		
		<h2>Managing functions</h2>
		
		<p>DBUtil allows you to create, rename, alter and drop database fields.</p>
		
		<article>
			<h4 id="method_create_database">create_database($database, charset = null)</h4>
			<p>The <strong>create_database</strong> method creates a database.  Will throw a Database_Exception if it cannot.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$database</kbd></th>
									<td><em>required</em></td>
									<td>the database name</td>
								</tr>
								<tr>
									<th><kbd>$charset</kbd></th>
									<td><em>null</em></td>
									<td>the default charset</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Create a database named `my_database`
DBUtil::create_database('my_database');

// Catch the exception
try
{
	DBUtil::create_database('my_database');
}
catch(\Database_Exception $e)
{
	// Creation failed...
}

// You can also set a default charset.
// CREATE DATABASE `new_database` DEFAULT CHARACTER SET 'utf8'
DBUtil::create_database('new_database', 'utf8');

// CREATE DATABASE `new_database  DEFAULT CHARACTER SET 'utf8' COLLATE 'utf8_unicode_ci'
DBUtil::create_database('new_database', 'utf8_unicode_ci');
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
			<p>If no charset is provided it will fall back to the charset of the active db group.</p>
		</article>
		
		<article>
			<h4 id="method_drop_database">drop_database($database)</h4>
			<p>The <strong>drop_database</strong> method drops a database.  Will throw a Database_Exception if it cannot.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$database</kbd></th>
									<td><em>required</em></td>
									<td>the database name</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Drop a database named `my_database`
DBUtil::drop_database('my_database');

// Catch the exception
try
{
	DBUtil::drop_database('my_database');
}
catch(\Database_Exception $e)
{
	// Drop failed...
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_drop_table">drop_table($table)</h4>
			<p>The <strong>drop_table</strong> method drops a table.  Will throw a Database_Exception if it cannot.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>the table name</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Drop a table named `my_table`
DBUtil::drop_table('my_table');

// Catch the exception
try
{
	DBUtil::drop_table('my_table');
}
catch(\Database_Exception $e)
{
	// Drop failed...
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
	
		<article>
			<h4 id="method_rename_table">rename_table($table, $new_table_name)</h4>
			<p>The <strong>rename_table</strong> method renames a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>The old table name</td>
								</tr>
								<tr>
									<th><kbd>$new_table_name</kbd></th>
									<td><em>required</em></td>
									<td>The new table name</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Rename `my_table` to `my_new_table`
DBUtil::rename_table('my_table', 'my_new_table');

// Catch the exception
try
{
	DBUtil::rename_table('my_table', 'my_new_table');
}
catch(\Database_Exception $e)
{
	// Rename failed...
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
	
		<article>
			<h4 id="method_create_table">create_table($table, $fields, $primary_keys = array(), $if_not_exists = true, $engine = false, $charset = null)</h4>
			<p>The <strong>create_table</strong> method creates a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>the table name</td>
								</tr>
								<tr>
									<th><kbd>$fields</kbd></th>
									<td><em>required</em></td>
									<td>array containing fields</td>
								</tr>
								<tr>
									<th><kbd>$primary_keys</kbd></th>
									<td><strong>array()</strong></td>
									<td>array containing primary keys</td>
								</tr>
								<tr>
									<th><kbd>$if_not_exists</kbd></th>
									<td><strong>true</strong></td>
									<td>whether to use <em>IF NOT EXISTS</em></td>
								</tr>
								<tr>
									<th><kbd>$engine</kbd></th>
									<td><strong>false</strong></td>
									<td>which storage engine to use (MyISAM, InnoDB, ...)</td>
								</tr>
								<tr>
									<th><kbd>$charset</kbd></th>
									<td><strong>null</strong></td>
									<td>the default charset, falls back to the active db group charset</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>\DBUtil::create_table('users', array(
	'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
	'name' => array('type' => 'text'),
	'email' => array('constraint' => 50, 'type' => 'varchar'),
	'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mr.'),
	'password' => array('constraint' => 125, 'type' => 'varchar'),
), array('id'), false, 'InnoDB', 'utf8_unicode_ci');
</code></pre>
						</td>
					</tr>
					<tr>
						<th>Possible parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>name</kbd></th>
									<td>the field name</td>
								</tr>
								<tr>
									<th><kbd>type</kbd></th>
									<td>field type (varchar, enum, text, ...)</td>
								</tr>
								<tr>
									<th><kbd>constraint</kbd></th>
									<td>Length or values.</td>
								</tr>
								<tr>
									<th><kbd>charset</kbd></th>
									<td>field charset</td>
								</tr>
								<tr>
									<th><kbd>unsigned</kbd></th>
									<td>boolean, <em>true</em> if is unsigned, defaults to <em>false</em></td>
								</tr>
								<tr>
									<th><kbd>default</kbd></th>
									<td>default value</td>
								</tr>
								<tr>
									<th><kbd>null</kbd></th>
									<td>boolean, <em>true</em> if nullable, defaults to <em>false</em></td>
								</tr>
								<tr>
									<th><kbd>auto_increment</kbd></th>
									<td>set to <em>true</em> to use auto incrementing</td>
								</tr>
							</table>
						</td>
					</tr>
				</tbody>
			</table>
			
			<p>Default fields values are escaped by default. In some cases you might want not to escape this value. If so, you can use <a href="./db.html#method_escape">DB::escape</a>.</p>
			<pre class="php"><code>\DBUtil::create_table('users', array(
	'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
	'name' => array('type' => 'text'),
	'email' => array('constraint' => 50, 'type' => 'varchar'),
	'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mr.'),
	'created' => array('type' => 'timestamp', 'default' => \DB::expr('CURRENT_TIMESTAMP')),
	'password' => array('constraint' => 125, 'type' => 'varchar'),
), array('id'));
</code></pre>
			
			<p>Escaping values work the same for DBUtil::add_fields and DBUtil::modify_fields</p>
			
		</article>
		
		<article>
			<h4 id="method_add_fields">add_fields($table, $fields)</h4>
			<p>The <strong>modify_fields</strong> method adds fields to a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>the table name</td>
								</tr>
								<tr>
									<th><kbd>$fields</kbd></th>
									<td><em>required</em></td>
									<td>array containing fields</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>\DBUtil::add_fields('users', array(
	'surname' => array('constraint' => 100, 'type' => 'varchar'),
	'twitter_name' => array('constraint' => 100, 'type' => 'varchar'),
));
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_drop_fields">drop_fields($table, $fields)</h4>
			<p>The <strong>drop_fields</strong> method drops fields from a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>string of the table name</td>
								</tr>
								<tr>
									<th><kbd>$fields</kbd></th>
									<td><em>required</em></td>
									<td>string or array containing fields</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>\DBUtil::drop_fields('users', 'surname');</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_modify_fields">modify_fields($table, $fields)</h4>
			<p>The <strong>modify_fields</strong> method alters fields in a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td>the table name</td>
								</tr>
								<tr>
									<th><kbd>$fields</kbd></th>
									<td><em>required</em></td>
									<td>array containing fields</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception on failure</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>\DBUtil::modify_fields('users2', array(
	'name' => array('constraint' => 100, 'type' => 'varchar', 'charset' => 'utf8_general_ci'),
	'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mrs.'),
));
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<h2 id="database-operations">Database operations</h2>
					
		<article>
			<h4 id="method_truncate_table">truncate_table($table)</h4>
			<p>The <strong>truncate_table</strong> method truncates a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td class="description">the table name.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Returns the number of affected rows.</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>\Database_Exception when not supported</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>\DBUtil::truncate_table('my_table');</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
	
		<article>
			<h4 id="method_analyze_table">analyze_table($table)</h4>
			<p>The <strong>analyze_table</strong> method analyzes a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td class="description">the table name.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td><em>True</em> if the table is OK. <em>False</em> when needs attention. If not supported it logs the error message.</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>if(\DBUtil::analyze_table('table_name') === false)
{
	// Do something
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_check_table">check_table($table)</h4>
			<p>The <strong>check_table</strong> method checks a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td class="description">the table name.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td><em>True</em> if the table is OK. <em>False</em> when needs attention. If not supported it logs the error message.</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>if(\DBUtil::check_table('table_name') === false)
{
	// Do something
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_optimize_table">optimize_table($table)</h4>
			<p>The <strong>check_table</strong> method optimizes a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td class="description">the table name.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td><em>True</em> if the table is OK or optimized. <em>False</em> on failure. If not supported or failed it logs the error message.</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>if(\DBUtil::optimize_table('table_name') === false)
{
	// Do something
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
		<article>
			<h4 id="method_repair_table">repair_table($table)</h4>
			<p>The <strong>check_table</strong> method repairs a table.</p>
			<table class="method">
				<tbody>
					<tr>
						<th>Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$table</kbd></th>
									<td><em>required</em></td>
									<td class="description">the table name.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td><em>True</em> if the table is OK or repaired. <em>false</em> on failure. If not supported or failed it logs the error message.</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>if(\DBUtil::repair_table('table_name') === false)
{
	// Do something
}
</code></pre>
						</td>
					</tr>
				</tbody>
			</table>
		</article>
		
	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>